TransformerForRuleReplacements = [Transformer]

The TransformerForRuleReplacements() method provides access to a special meta-transformer. This transformer does not process normal text; instead, it processes the replacement strings (the To part) of rules you define with FromTo().

This allows you to create powerful shorthands, aliases, or macros for your replacement logic, promoting consistency and readability in complex transformation projects.

⚙️ How It Works

When you define a rule like t.FromTo(pattern, replacement), the replacement string is first passed through the meta-transformer returned by this method. The result of that transformation is what gets compiled as the final replacement rule.

using uCalcSoftware;

var uc = new uCalc();

// 1. Get the meta-transformer
var meta = uc.TransformerForRuleReplacements();

// 2. Define a meta-rule: "#b({c})" will become "<b>{c}</b>"
//    Note: {@Eval:'...'} is used to pass the replacement as a literal template.
meta.FromTo("#b({c})", "{@Eval:'<b>{c}</b>'}");

// 3. Create a standard transformer
var t = new uCalc.Transformer();

// 4. Use the shorthand in a normal rule definition.
//    The meta-transformer will expand "#b({word})" before this rule is compiled.
t.FromTo("{@Alpha:word}", "#b({word})");

// 5. The rule effectively becomes: t.FromTo("{@Alpha:word}", "<b>{word}</b>");
Console.WriteLine(t.Transform("make this bold"));
// Output: make this <b>bold</b>

💡 Core Use Cases

• Creating Aliases: Define a short alias like ~ to represent a common but verbose placeholder like {@Self}.
• Building Macros: Create complex, reusable replacement templates (e.g., for wrapping text in HTML/XML tags).
• Enforcing Consistency: Ensure all replacement strings follow a standard format by pre-processing them.

⚠️ Critical Pitfall: Premature Variable Evaluation

When defining a meta-rule, its replacement string can contain variable placeholders intended for the final rule (e.g., {c} in the example above). To prevent the meta-transformer from trying to evaluate these placeholders itself, you must wrap the replacement template in {@Eval:'...'}. This treats the template as a literal string, ensuring the placeholders are preserved for the final rule.

• Incorrect: meta.FromTo("#b({c})", "<b>{c}</b>") - The meta-transformer will look for a variable named c.
• Correct: meta.FromTo("#b({c})", "{@Eval:'<b>{c}</b>'}") - The meta-transformer inserts the literal string <b>{c}</b>.

Comparative Analysis

• vs. Manual Replacement: You could manually type <b>{word}</b> every time, but using a meta-transformer abstracts this logic. If you later decide to use <strong> tags instead of <b>, you only need to change the single meta-rule, and all dependent rules update automatically.
• vs. Text Pre-processors (C/C++): This feature is analogous to a C pre-processor #define macro, but it's fully integrated into the uCalc engine, token-aware, and can be modified dynamically at runtime.

This meta-transformer is not created until TransformerForRuleReplacements() is called for the first time, ensuring no performance overhead if the feature is unused. It is the direct counterpart to TransformerForRulePatterns(), which performs the same function for pattern strings.